---
title: 모델
description: Choose and configure language models for your agents
---

import { Code } from '@astrojs/starlight/components';
import modelCustomProviderExample from '../../../../../../examples/docs/models/customProviders.ts?raw';
import setDefaultOpenAIKeyExample from '../../../../../../examples/docs/config/setDefaultOpenAIKey.ts?raw';
import modelSettingsExample from '../../../../../../examples/docs/models/modelSettings.ts?raw';
import promptIdExample from '../../../../../../examples/basic/prompt-id.ts?raw';
import agentWithModelExample from '../../../../../../examples/docs/models/agentWithModel.ts?raw';
import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw';
import gpt5DefaultModelSettingsExample from '../../../../../../examples/docs/models/gpt5DefaultModelSettings.ts?raw';
import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';

모든 에이전트는 궁극적으로 LLM을 호출합니다. SDK는 두 개의 경량 인터페이스 뒤에 모델을 추상화합니다:

- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 특정 API에 대해 _하나의_ 요청을 수행하는 방법을 알고 있음
- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 사람이 읽을 수 있는 모델 **이름**(예: `'gpt‑4o'`)을 `Model` 인스턴스로 해석

일상적인 작업에서는 일반적으로 모델 **이름**과 때때로 `ModelSettings`만 다룹니다.

<Code
  lang="typescript"
  code={agentWithModelExample}
  title="에이전트별 모델 지정"
/>

## 기본 모델

`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)로, 에이전트 워크플로를 위한 예측 가능성과 낮은 지연 시간 간의 균형이 뛰어납니다.

[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)와 같은 다른 모델로 전환하려면 두 가지 방법이 있습니다.

먼저, 사용자 지정 모델을 설정하지 않은 모든 에이전트에서 일관되게 특정 모델을 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.

```bash
export OPENAI_DEFAULT_MODEL=gpt-5
node my-awesome-agent.js
```

둘째, `Runner` 인스턴스에 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않은 경우, 이 `Runner`의 기본 모델이 사용됩니다.

<Code
  lang="typescript"
  code={runnerWithModelExample}
  title="Runner에 기본 모델 설정"
/>

### GPT-5 모델

이 방식으로 GPT-5의 reasoning 모델([`gpt-5`](https://platform.openai.com/docs/models/gpt-5), [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini), [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano))을 사용할 때, SDK는 합리적인 기본 `modelSettings`를 적용합니다. 구체적으로 `reasoning.effort`와 `verbosity`를 모두 `"low"`로 설정합니다. 기본 모델의 reasoning effort를 조정하려면, 직접 `modelSettings`를 전달하세요:

<Code
  lang="typescript"
  code={gpt5DefaultModelSettingsExample}
  title="GPT-5 기본 설정 사용자화"
/>

더 낮은 지연 시간을 위해 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)를 `reasoning.effort="minimal"`로 사용하면 기본 설정보다 더 빠르게 응답하는 경우가 많습니다. 다만 Responses API의 일부 기본 제공 도구(예: 파일 검색 및 이미지 생성)는 `"minimal"` reasoning effort를 지원하지 않으므로, 이 Agents SDK의 기본값은 `"low"`입니다.

### 비 GPT-5 모델

사용자 지정 `modelSettings` 없이 비 GPT-5 모델 이름을 전달하면, SDK는 모든 모델과 호환되는 일반적인 `modelSettings`로 되돌립니다.

---

## OpenAI 프로바이더

기본 `ModelProvider`는 OpenAI API를 사용해 이름을 해석합니다. 두 가지 별도의 엔드포인트를 지원합니다:

| API              | 사용법                                                | `setOpenAIAPI()` 호출                  |
| ---------------- | ----------------------------------------------------- | -------------------------------------- |
| Chat Completions | 표준 채팅 및 함수 호출                                | `setOpenAIAPI('chat_completions')`     |
| Responses        | 스트리밍 우선의 신규 생성 API(도구 호출, 유연한 출력) | `setOpenAIAPI('responses')` _(기본값)_ |

### 인증

<Code
  lang="typescript"
  code={setDefaultOpenAIKeyExample}
  title="기본 OpenAI 키 설정"
/>

맞춤 네트워킹 설정이 필요하면 `setDefaultOpenAIClient(client)`를 통해 자체 `OpenAI` 클라이언트를 연결할 수 있습니다.

---

## ModelSettings

`ModelSettings`는 OpenAI 파라미터를 반영하지만 프로바이더에 종속되지 않습니다.

| Field               | Type                                       | Notes                                                                      |
| ------------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| `temperature`       | `number`                                   | 창의성 대 결정론                                                           |
| `topP`              | `number`                                   | 누클리어스 샘플링                                                          |
| `frequencyPenalty`  | `number`                                   | 반복 토큰에 대한 패널티                                                    |
| `presencePenalty`   | `number`                                   | 새로운 토큰 장려                                                           |
| `toolChoice`        | `'auto' \| 'required' \| 'none' \| string` | [도구 사용 강제](/openai-agents-js/ko/guides/agents#forcing-tool-use) 참고 |
| `parallelToolCalls` | `boolean`                                  | 지원되는 경우 병렬 함수 호출 허용                                          |
| `truncation`        | `'auto' \| 'disabled'`                     | 토큰 절단 전략                                                             |
| `maxTokens`         | `number`                                   | 응답의 최대 토큰 수                                                        |
| `store`             | `boolean`                                  | 검색/RAG 워크플로를 위해 응답을 보존                                       |
| `reasoning.effort`  | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 등에서의 reasoning effort                                            |
| `text.verbosity`    | `'low' \| 'medium' \| 'high'`              | gpt-5 등에서의 텍스트 장황도                                               |

설정은 어느 수준에서든 첨부할 수 있습니다:

<Code lang="typescript" code={modelSettingsExample} title="모델 설정" />

`Runner` 수준의 설정은 에이전트별 설정과 충돌하는 경우 이를 우선합니다.

---

## 프롬프트

에이전트는 `prompt` 매개변수로 구성할 수 있으며, 이는 서버에 저장된 프롬프트 구성을 사용해 에이전트의 동작을 제어해야 함을 나타냅니다. 현재 이 옵션은 OpenAI [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용할 때만 지원됩니다.

| Field       | Type     | Notes                                                                                                      |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `promptId`  | `string` | 프롬프트의 고유 식별자                                                                                     |
| `version`   | `string` | 사용하려는 프롬프트 버전                                                                                   |
| `variables` | `object` | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일과 같은 콘텐츠 입력 타입일 수 있음 |

<Code
  lang="typescript"
  code={promptIdExample}
  title="프롬프트가 있는 에이전트"
/>

도구나 instructions 같은 추가 에이전트 구성은 저장된 프롬프트에서 구성한 값을 재정의합니다.

---

## 사용자 지정 모델 프로바이더

자체 프로바이더 구현은 간단합니다 – `ModelProvider`와 `Model`을 구현하고, 프로바이더를 `Runner` 생성자에 전달하세요:

<Code
  lang="typescript"
  code={modelCustomProviderExample}
  title="최소한의 사용자 지정 프로바이더"
/>

---

## 트레이싱 익스포터

OpenAI 프로바이더를 사용할 때 API 키를 제공해 자동 트레이스 내보내기를 선택할 수 있습니다:

<Code
  lang="typescript"
  code={setTracingExportApiKeyExample}
  title="트레이싱 익스포터"
/>

이는 [OpenAI 대시보드](https://platform.openai.com/traces)로 트레이스를 전송하며, 워크플로의 전체 실행 그래프를 확인할 수 있습니다.

---

## 다음 단계

- [에이전트 실행](/openai-agents-js/ko/guides/running-agents)을 살펴보세요
- [도구](/openai-agents-js/ko/guides/tools)로 모델에 초능력을 부여하세요
- 필요에 따라 [가드레일](/openai-agents-js/ko/guides/guardrails) 또는 [트레이싱](/openai-agents-js/ko/guides/tracing)을 추가하세요
